Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Manipulating Shape Object Properties

GXSetShapeTags

You can use the GXSetShapeTags function to add, remove, or replace tag objects associated with a shape object.

void GXSetShapeTags(gxShape target, long tagType, long index, 
                  long oldCount, long newCount, 
                  const gxTag items[]);

target

A reference to the shape object to alter the tag list of.

tagType

The type of tag objects to replace. A value of 0 indicates that you want to replace tags of all types.

index

The (1-based) index of the first tag reference (to a tag object of the appropriate type) to replace.

oldCount

The number of tag references to replace. A value of 0 specifies that you want to insert tag references before the tag reference indicated by the index parameter, rather than replace tag references. A value of -1 (the gxSelectToEnd constant) specifies that all tag references of the requested type, starting with the tag reference indicated by the index parameter, should be replaced.

newCount

The number of tag references to insert. A value of 0 specifies that there are no tag references to insert; the existing tag references that match the criteria you specify are removed from the source shape's tag list and disposed of.

items

An array of tag references to insert in the tag list.

DESCRIPTION

The GXSetShapeTags function allows you to add tag references to a shape object's tag list, to remove tag references from the list, or to replace tag references in the list with new tag references. In any of these three cases, the target parameter specifies the shape object to be modified, the newCount parameter specifies the number of tag references to add, and the items parameter provides the new tag references.

• To add tag references, set the oldCount parameter to 0. Use the tagType and the index parameters to specify where to add the new tag references. (For example, if you specify nil for the tagType parameter and 1 for the index parameter, this function inserts the new tag references before the current tag references. If you specify a value other than nil for the tagType parameter and a value of 2 for the index parameter, the function inserts the new tag references before the second tag reference with a tag type matching the tagType parameter.)
• To remove tag references, set the newCount parameter to 0 and the items parameter to nil. You can use the index and the oldCount parameters to specify which tag references (of the specified type) should be removed. The index parameter indicates the first tag reference (of the specified type) to remove and the oldCount parameter indicates how many tag references (of the specified type) to remove.
• To replace tag references, use the tagType, index, and oldCount parameters to indicate which tag references to replace, and use the newCount and items parameters to specify the new tag references to add. If newCount is greater than oldCount, the extra tag references are placed immediately adjacent to the last tag reference replaced.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
tag_is_nil
parameter_is_nil	(debugging version)
inconsistent_parameters	(debugging version)
parameter_out_of_range	(debugging version)
index_is_less_than_zero	(debugging version)
cannot_dispose_locked_tag	(debugging version)
Warnings
index_out_of_range
count_out_of_range
Notices (debugging version)
tag_already_set

SEE ALSO

Tag objects are introduced in the chapter "Introduction to Objects" in this book. Functions to create and manipulate tags objects, and a list of reserved tag types, are described in the chapter "Tag Objects" in this book.

To examine the set of tag references associated with a shape, use the GXGetShapeTags function, described in the previous section.